<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] Custom Connections</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font
size="+1">Custom Connections</font></b></center>

<p><a name="intro"></a><b>Introduction</b></p>

<p>Normally, retawq tries to handle all network activity in a completely
automated way: you only enter a <a href="scheme.html">URL</a>, e.g. with the <a
href="key.html">keyboard command</a> "g", and the program connects to a server
and handles the network commands and responses as appropriate for the
respective protocol. But in some cases, you might want to "customize" the
sequence of network commands manually, e.g. because you want to access a server
which requires special commands or special sequences of commands to get a
certain job done. That's what the "custom connections" feature is for. It
provides a functionality similar to that of the usual, old, shell-like FTP
clients.</p>

<p>Please note that this feature is very young - introduced in version 0.2.6 -
and might not yet work as expected.</p>

<p>To use custom connections, start the program in console <a
href="runmode.html">runmode</a> with the <a href="arg.html">command-line
option</a> "--console". You are provided with a text prompt on a "raw" text
console which doesn't use any curses library support, similar to usual
shell-like FTP clients. At the prompt, you can enter textual commands like
"open", "get", "help" or "quit".</p>

<p><a name="open"></a><b>Opening a Connection</b></p>

<p>To open a connection to a server, enter the command "open" with one
argument. Deviating from usual shell-like FTP clients, the argument isn't a
bare server name but instead a <a href="scheme.html">URL</a> which consists of
a scheme and the actual server name and, optionally, a port number. If no
explicit scheme is given, FTP is assumed here. Some example commands: "open
foo.org", "open ftp://foo.org", "open ftp.foo.org", "open ftp.foo.org:42",
"open ftps://ftp.foo.org/".</p>

<p>The following schemes are currently "known" for custom connections:</p>
<ul>
<li>The scheme "ftp" is supported; this behaves similar to the usual shell-like
FTP clients. If no explicit port number is given, the default FTP port (21) is
used.</li>
<li>If the <a href="ctconfig.html">compile-time configuration option</a>
OPTION_TLS has been enabled: 1. The scheme "ftps" is supported; if no explicit
port number is given, the default ftps port (990) is used; with this scheme, a
<a href="tls.html">TLS/SSL</a> handshake is automatically performed as soon as
the connection to the server has been established. 2. With the normal "ftp"
scheme, you can start a TLS/SSL handshake at any later time manually using an
"auth" command.</li>
</ul>

<p>When a connection has been established, you <i>usually</i> want to enter the
commands "user" and "pass", followed by some sequence of "cd", "ls", "binary"
and "get" or other commands. When you are done with a connection, use a "close"
command.</p>

<p><a name="task"></a><b>Tasks</b></p>

<p>Deviating from most shell-like FTP clients, retawq allows you to operate on
several connections at the same time for extra comfort and flexibility. In
console runmode, each (control) connection is represented by a "task". Each
task is identified by a unique "task identification number" ("task ID"). The
task ID of the current task (if any) is shown in the prompt string.</p>

<p>Whenever you open a new connection, e.g. with an "open" command, a new task
is created. To get a list of all currently existing tasks or information about
specific tasks, use the command "info". To switch to a different task, select
it with the command "task". If the current task is busy and you want to get a
prompt, press the key "&amp;". (Mnemonic: that's the key which you use at the
end of a line in a normal shell to execute a job in the background.)</p>

<p><a name="cmd"></a><b>Commands</b></p>

<p>The below textual commands are available for the handling of custom
connections. Some commands may or must have arguments; commands and any
arguments are separated by space characters; if a command requires a certain
number of arguments, this is mentioned in parentheses. At run-time, you can get
a list of available commands by using the command "help" without arguments, and
you can get short information about specific commands by using the command
"help" with the respective commands as arguments. You'll notice that some usual
commands like "put" are currently missing - they will be implemented in a
future version.</p>

<p>Many servers accept some of the commands only if you are logged in as a
"real" (non-anonymous) user - especially commands which change something on the
server file system, e.g. delete, mkdir, rmdir.</p>

<p>Commands may be abbreviated as far as they don't become ambiguous; for
example, the command "quote" may be abbreviated to "quo", but not further
("qu", "q") because this could be mixed up with "quit".</p>

<p>To discard the current input for a command in console runmode, press
ctrl-c.</p>

<ul>
<li>account - send your "account" information to the server (1 argument); this
is necessary with some servers if you want to put/upload files to them; you
might have to use this command right after a "pass" command or at some point
before a "put" command</li>
<li>ascii - set the file transfer type for the current connection to ASCII (0
arguments)</li>
<li>auth - start a <a href="tls.html">TLS/SSL</a> handshake on the current
connection (0..1 arguments); this command is only available if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_TLS has been
enabled. If you have opened a connection using the <a href="scheme.html">URL
scheme</a> "ftp" (not "ftps"!), you can start the handshake at any later time
manually with this command. If you don't provide an argument, the handshake is
either performed as specified with the <a href="rtconfig.html">run-time
configuration option</a> "ftps-method" or, by default, autodetected.
Alternatively, you can explicitly provide a single-letter argument which
corresponds to FTP commands and "ftps-method" identifiers as follows:
<ul>
<li>"p": "AUTH TLS", "PROT P"; authtls</li>
<li>"c": "AUTH TLS", "PROT C"; authtls-dataclear (so <i>the data connection
won't be protected</i> with this method)</li>
<li>"s": "AUTH SSL"; authssl</li>
</ul>
If any problem occurs in the sequence of the FTP commands which establish TLS,
the control connection probably becomes unusable, so you should close it and
open a new one.</li>
<li>binary - set the file transfer type for the current connection to binary (0
arguments)</li>
<li>cd - change the remote current working directory to the given directory (1
argument)</li>
<li>cdup - change to the remote parent directory (0 arguments); this has quite
the same effect as "cd .."</li>
<li>close - close the current connection (if no arguments are given) resp.
close all connections whose task IDs are given as arguments</li>
<li>delete - delete the given remote file (1 argument)</li>
<li>download - download the content from the <a href="scheme.html">URL</a>
which is given in the first argument and store it in a local file (1..2
arguments); the file name can be provided in the optional second argument; if
no explicit file name is given, retawq tries to extract a file name from the
URL - if that's not possible, you get a "too few arguments" error message and
can re-enter the command with an explicit file name. The download is performed
in a new task, so you can observe its progress with the command "info" or stop
it with the command "close". Unlike the command "get", the command "download"
performs an automated download similar to the <a href="arg.html">command-line
option</a> "--download" and the <a href="key.html">keyboard command</a>
"ctrl-d"; this has the following consequences: 1. you can use <i>any</i> <a
href="scheme.html">URL</a> which would be allowed with the <a
href="key.html">keyboard command</a> "ctrl-d", so you aren't restricted to FTP;
2. you can't "customize" the operation and can't get at a prompt for such a
download task; 3. there's no need to open a connection manually with an
explicit prior "open" command.</li>
<li>get - receive one file from the server and save it in a local file (1..2
arguments); the first argument must be the remote file name, the optional
second argument is a local file name; if the second argument is missing, the
file name part from the first argument is used if possible, or you get a "too
few arguments" error message and can re-enter the command with an explicit file
name. If a local file with the name already exists, you're asked whether you
want to overwrite or append (or cancel); enter one of the letters which are
provided in parentheses - any other input is interpreted as "cancel" - and
press Return. If you want to append, you presumably want use the command
"restart" before "get".</li>
<li>hash - if no argument is given, toggle the printing of hashmarks ("#")
on/off; by default, hashmark printing is off; when turned on, one hashmark is
printed for every "chunk" of data that is transferred in the current
connection, which usually means 1024 transferred bytes; if the argument is a
question mark ("?"), the current hashmark mode is shown without modification;
if a numerical argument of at least 256 is given, this is interpreted as the
new "chunk size" and hashmark printing is turned on; otherwise, hashmark
printing is turned off (0..1 arguments)</li>
<li>help - print a list of all available commands (if no arguments are given)
resp. print short information about all commands which are given as arguments;
alias for this command: "?" (as in other shell-like FTP clients)</li>
<li>info - show information about all existing tasks (if no arguments are
given) resp. about the tasks whose task IDs are given as arguments; the
information for each task consists of one or two lines: the first line mentions
the ID number, the label (if any), the state (busy/automated), TLS protection
and the server URL; a second line might describe the current state of the
connection, similar to the information in the bottom line of the screen in
curses-like <a href="runmode.html">runmode</a> - for custom connections, it
usually says "Exchanging messages" plus the last server status code (FTP server
reply code).</li>
<li>label - mark a task with a "label" (an arbitrary string which doesn't begin
with a digit and doesn't contain whitespace characters); the first argument is
the label string; the optional second argument is the task ID of the task to
which the label shall be attached; if no task ID is given, the label is
attached to the current task. The labels can help you to find certain tasks in
long task lists faster and can be memorized more easily than the somewhat
abstract task ID numbers. (Thus further uses of labels are planned for future
releases.)</li>
<li>lcd - change the local current working directory (0..1 arguments); if no
argument is given, the working directory is changed back to the original
directory which was current when the program was started; if one argument is
given, this is used as the new current working directory; if you only want to
find out what the current working directory is without modifying it, you can
use "lcd&nbsp;."; all tasks use the same local current working directory, so
you don't have to enter this command for every new task</li>
<li>ls - list the contents of the current remote working directory (if no
argument is given) or the contents of the given directory; depending on the
server, you might be able to use list options like "-aL"</li>
<li>mkdir - make (create) the given remote directory (1 argument)</li>
<li>open - open a connection to a server which is specified via URL; this
creates a new task; read the section "Opening a Connection" above for an
extensive discussion of this command (1 argument)</li>
<li>pass - send a password to the server for login (0..1 arguments); this must
usually be done right after a "user" command, and most FTP servers require
these commands to occur in this order without any other commands in between. If
you don't mind anyone near you reading the password on the screen, you can
enter the password directly as an argument to the "pass" command; otherwise,
use the "pass" command without any arguments and you're prompted separately for
the password, where all entered characters appear as disguising "*" characters
on the screen. If the username was "anonymous", the password must usually be
"guest" or "anonymous" or look like an e-mail address. - If a server produces
very long multi-line messages when you login or whenever you change the remote
current working directory etc., it might help if you stick a dash ("-")
immediately in front of the password; many servers understand this and produce
much shorter messages afterwards.</li>
<li>pwd - print the remote current working directory (0 arguments)</li>
<li>quit - quit the program immediately (0 arguments); aliases for this
command: "bye", "exit" (as in other shell-like FTP clients)</li>
<li>quote - send a verbatim FTP command to the server; this allows you to send
arbitrary FTP commands, even those which retawq doesn't know anything about.
The FTP command is neither modified nor analyzed; the disadvantage is that
retawq can't know what's going on, so it can only recognize the time at which
the server sent a complete response back and prompt you for the next command;
e.g. you can't use quoted commands to start a file transmission because retawq
would have to extract the IP address and port number for the data connection
from the text; similarly you can't use quoted commands to start a TLS/SSL
handshake.</li>
<li>restart - set the server's file transfer restart marker to the given value
(1 argument); this command usually must be followed by a command like "get" to
initiate an actual file transfer</li>
<li>rmdir - remove (delete) the given remote directory (1 argument)</li>
<li>site - send a site-specific command to the server (1 or more arguments);
the possible site-specific commands depend on the server; you might be able to
get further information with a command like "site help" or "quote help site";
one particularly useful site command is "site chmod", which might allow you to
change the access permissions of a remote file</li>
<li>task - switch to (select) the given task (1 argument); if the given task is
currently "busy", you don't get a prompt but you can use the key "&amp;" as
described in the section "Tasks" above</li>
<li>user - send the given argument as a username to the server for login; if
you don't provide an argument, "anonymous" is sent; please note that you aren't
automatically prompted for a password afterwards - use the "pass" command
manually if necessary; this whole feature is about <i>custom</i> connections,
so it tries to do as little as possible automatically (0..1 arguments)</li>
<li>version - show retawq's version number</li>
<li>! (exclamation mark) - execute a shell command; for security reasons, this
only works if the respective feature has been enabled with the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_EXECEXT. This
command is similar to the <a href="key.html">keyboard command</a> "!".
Especially, the first argument can be an "options" argument introduced with a
colon (":"); but since console runmode doesn't have anything like a "current
document" notion, you can only use the options "o", "e" and "h" here. If you
use one of the options for reading the output of the shell command, a new task
is created for this, so you can switch to a different task if the shell command
is busy for a longer time and you don't want to wait; otherwise, the shell
command is executed "asynchronously in the background" and its output is
discarded.</li>
</ul>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
